Celestin Apprentice 5/Apprentice-Release5.iso/Source Code/Libraries/CW GUSI 1.6.4/README

Text File | 1995-11-06 | 22KB | 497 lines

                 G U S I -- Grand Unified Socket Interface

INTRODUCTION

GUSI is an extension and partial replacement of the standard C runtime library
supplied with your compiler. Its main objective is to provide a more or less
simple and consistent interface across the following communication domains:

Files                Ordinary Macintosh files and MPW pseudo devices.
Unix                Memory based communication within a single machine.
Appletalk        ADSP communication over a network.
PPC                Connections with the System 7 PPC Toolbox.
Internet            TCP and UDP connections over MacTCP.
PAP                 Connections to PostScript printers.

Additionally, GUSI adds some UNIX library calls dealing with files which were
missing, like chdir(), getcwd(), symlink(), and readlink(), and changes a few
other library calls to behave more like their POSIX counterparts.

REQUIREMENTS

To use GUSI with Metrowerks CodeWarrior, you need CW/5.5 or later. For the
current version, you need CW/6.

COPYING

Copyright © 1992-1995 Matthias Neeracher

Permission is granted to anyone to use this software for any purpose on any
computer system, and to redistribute it freely, subject to the following
restrictions:

- The author is not responsible for the consequences of use of this software,
  no matter how awful, even if they arise from defects in it.
- The origin of this software must not be misrepresented, either by explicit
  claim or by omission.
- Altered versions must be plainly marked as such, and must not be misrepresented
  as being the original software.

DOCUMENTATION

GUSI documentation is written in .pod format, a markup format used for Perl 5
documentation. From the .pod version, a HTML version for online documentation and
an RTF version for hardcopy is generated. From the RTF Version, the PDF version
is generated. Depending on packaging, the archive you received contains

- A directory :pod: with the pod files.
- A file GUSI.rtf with the RTF version.
- A file GUSI.pdf with the PDF version.

WHERE TO BEGIN

You should probably start by looking at the documentation. Maybe
it helps also to play with the sample programs.

BUGS, QUESTIONS, SUGGESTIONS

Please report any problems you experience with the code or the documentation to
me. I'd also be interested in hearing about your success stories, if you have
any.

GUSI ON WWW

An online version of the GUSI manual and a GUSI FAQ are available at
http://err.ethz.ch/members/neeri/macintosh.html

MAILING LIST

There is a mailing list for announcing new releases and discussions about
how to make GUSI change your life. To subscribe, send a mail:

----------------------------------
To: [e-mail]
Subject: (is ignored)

subscribe
----------------------------------

Mail is now processed by a daemon, so please follow the above format.

Matthias Neeracher                    Office:    [phone]
Hohenklingenstrasse 19                Fax:        [phone]
8049 Zuerich                            Home:     [phone]
SWITZERLAND                                Email:    <[e-mail]>

RELEASE NOTES

Version 1.6.4        05Nov95

- Include experimental support for CFM68K. I don't have any 68K Macs for
  testing, so this needs your feedback.
- Be even more careful about alignment.
- Avoid calling spin function from select immediately before returning
  [Ray Johnson].
- readlink() no longer mounts network volumes or floppies. This means that while the
  result returned is identical, passing it to a file function might now fail in cases
  where it worked in earlier versions, but I think this version is much more
  useful overall [Martin Heller].
- '*' at the end of a wildcard pattern now works.

Version 1.6.3        09Oct95

- Fixed alignment problems with new universal header version

Version 1.6.2        04Sep95

- Built with CodeWarrior 1.3 final instead of beta release

Version 1.6.1        26Aug95

- Version for CodeWarrior Integrated Environment 1.3

Version 1.6.0        25Aug95

- When opening the console fails, Dev:Null is now opened instead [Ray Johnson].
- Added variant of TFileSpec::RelPath giving a relative path from an arbitrary
  directory.
- Made sure that not only open(), but also stat() works for the more common
  devices.
- Files are now opened with HOpenDF instead of HOpen, which should get rid of
  some embarassing crashes.
- singletons are now reference counted correctly.
- GUSIDispatchLib.68K contains a few more routines.
- Fixed a disastrous bug in configuration resource parsing.

Version 1.5.9        25Jun95

- GUSI now makes more of an effort to handle volumes named Dev: [Ray Johnson].
- Attacked a few problems occurring when GUSI was used from static initializers
  [Paddy Benson].
- Tried to assure that every struct declared in an external header is explicitely
  declared with 68K alignment  [Paddy Benson].
- Fixed a few more bugs in MPW tool support.

Version 1.5.8        05Jun95

- Changed C++ Style comment in sys/fcntl.h [Mark Roseman]
- Included instructions for repairing dnr.c in "dnr.c Patch".
- Introduced GUSIDispatch.Lib.68K, which is intended for use in single segment
  links, in particular MPW tools. GUSIDispatch.Lib contains all functions that
  absolutely *have* to be specified early in the link, so it suffices to include
  GUSIDispatch.Lib early, and you can include GUSI.Lib later in the link. Unless
  you're having "segment offset out of range" problems, you won't need this
  library.
- Included QUESTIONNAIRE. Please take the time to send in your response and
  direct the further development of GUSI.

Version 1.5.7        04Jun95

- Fixed some incompatibilities with Metrowerks C++ 1.2.2 [David Tarabar and several
  others].
- Further increased TCP buffers [Alec Carlson].

Version 1.5.6     04May95

- sleep() had the termination condition wrong [Adam Skwersky].
- GUSIDefaultSpin would interrupt a call if an unknown appleevent was sent
  [Brad Barber].
- Every header which uses the "macintosh" preprocessor symbol now ensures that
  it's defined properly.

Version 1.5.5        23Apr95

- Fixed creator of text files.

Version 1.5.5fc1    20Apr95

- Further error number reviewing.
- Reactivated the AF_UNIX domain. It's actually a pretty fast family for simgle
  machine communication.
- Added sleep(), usleep() and a relatively wimpy version of alarm().
- Simplified segmentation scheme to avoid the horror accidents that happened
  when people started renaming segments [Andrew Diseker].
- Cleaned up conditional defines. Now I'm using GENERATINGPOWERPC, GENERATING68K
  and GENERATINGCFM everywhere.
- Include dnr.c directly so TCP/IP client programs no longer have to do that.
- Fixed filename encoding.
- Make select call post_selects before interrupting.
- Make benchmark protocol used by bs/bc binary compatible with MPW version, no matter
  how \n is set.
- Fixed Mv and List in GUSIFileTest.c
- Updated documentation.

Version 1.5.5b5    11Apr95

- Reviewed the error numbers returned and should now be much more compliant with
  POSIX [Ray Johnson]. The documentation currently does not yet reflect these
  changes.
- Added files to the distribution that were forgotten in the previous version
  [Various Correspondents].
- Fixed guard define in netinet/in.h [Rolf-Stephan Badura].
- The project stationeries had subtle and not so subtle errors [John Deighan].
- Clarified the rebuilding instructions in README.CWGUSI [John Deighan].

Version 1.5.5b4 07Apr95

- Added MPW tool support.
- Added access() and GUSI_ExecHook [Ray Johnson].
- UDP sockets used to ignore packets sent to them before the first recv(); now they
  start accepting packets right after bind().
- Added PDF documentation [Ed Draper].

Version 1.5.5b3 21Mar95

- Improved SIOUX support [Patrick C. Beard].
- access() would misbehave if a client closed immediately agfter connecting
  [Jake Hill]
- Provided updated documentation, now available in GUSI.rtf. See above regarding
  an online version [Thanks to Martin Heller, who helped in several respects
  with this project].

Version 1.5.5b2 26Jan95

- The inline assembly functions in the 68K versions would return values in the
  wrong register.
- Fixed segmentation of 68K completion routines.
- Fixed interaction with SIOUX.

Version 1.5.5b1 25Jan95

- This is the first prerelease of the CodeWarrior port. See README.CW for what little
  documentation there currently is on CWGUSI.

Version 1.5.0    31Dec94

- Port GUSI to the PowerPC. This has had the useful side effect of making the
  source more portable to other compilers by eliminating some syntactic
  idiosyncrasies that MPW C was supporting and by moving the source to the
  universal headers.
- Improve handling of filename oriented calls. All calls taking file names as
  arguments are now fully dispatchable.
- Move support for David Peterson's Inetd into a separate file. The bad news is
  that you'll now have to explicitely request support for inetd, the good news
  is that the majority of GUSI clients will have a somewhat smaller burden linked
  in.
- Added routines for encoding FSSpecs into printable C strings.
- Fixed a horrible bug which would destroy certain path names on TFileSpec
  construction [John Liberty].
- Increased the TCP buffer size and inserted process manager wakeups into TCP code,
  both of which might improve performance; fixed a few more bugs in the TCP code
  [Mark Lanett and Stephan Deibel].
- Added documentation for TFileSpec.h
- Added routines to the test code to test request/reply throughput.
- Fixed a few minor bugs.
- Added chmod(). The only part of its functionality that is supported is the
  ability to lock a file [John Kamp].

Version 1.4.1    02May94

- Non-blocking sends on TCP sockets with large amounts of data would not do
  anything [Benjamin Beberness].

Version 1.4.0    01May94

- Enabled recvfrom with non-NULL from addresses on all stream socket families
  (returning getpeername()) to fix a problem with MacPerl [James Burgess,
  Asa Packer].
- Attempting to write on half open sockets would still sometimes hang because of
  the fflush() problem mentioned below. I had to extend the kludge to almost
  all possible error codes [Asa Packer].
- Permissions returned by stat() for locked files were wrong [John Kamp].
- Implemented utime() as far as possible (i.e., for modification times, the
  Mac has no concept of access times) [James Burgess].
- Another round in my epic battle with rename(): This time, rename() resolved
  aliases that should have been left unresolved [Maki Watanabe, Man Wei Tam].
- Avoided calls to malloc() on system startup to circumvent problems with
  MacPerl memory allocation [Sal Gurnani, Torsten Ekedahl et al.].
- Try to behave more sensibly when the other side closes a socket()
  [David Hansen].
- getservbyname() would fail unless /etc/services was in the preferences folder
  [Alasdair Rawsthorne].
- Switched from Projector to RCS.
- Tried to fix a compatibility problem with MPW 3.2

Version 1.3.6  22Feb94

- recvfrom wouldn't return the address of the sender [Michael Wu].
- TFileSpec constructors now preserve case, (hopefully) making rename("a","A")
  finally work [Maki Watanabe].
- rename() is now able to rename locked files. This is an experimental feature
  introduced to support RCS. It might go away again.

Version 1.3.5    11Jan94

- Made the semantics of select() conform more closely to their UN*X counter-
  parts. In particular, if there is no more data to read/write, a socket is
  now flagged as ready to read/write. In the past, the exception flag was
  incorrectly used to signal error conditions.
- EBADF is now treated the same way as ESHUTDOWN on write().
- GUSI now handles more than _NFILE stdio FILEs [James Tisdall].
- Fixed several bugs with default arguments and prompts for choose() with
  files [Maki Watanabe].
- chdir() would ignore most errors [Peter Lewis].

Version 1.3.4    17Nov93

- Fixed a bug in GUSIBuffer which prevented PPC Toolbox sockets from receiving
  more than about 2K of data before crashing.
- fflush() in the MPW stdio library doesn't take no (or -1) for an answer,
  therefore quitting with unsent data in the stdio buffers would cause programs
  to hang. As a workaround, GUSI detects when write() is called twice in a row
  and ESHUTDOWN would have been returned both times. In this case, GUSI pretends
  the write succeeded the second time.
- The new version of rename introduced in 1.3.3 was buggy in several respects.
  First of all, it would return EINVAL when the call actually had succeeded.
  Second, rename() was too naive to actually force the correct spelling.
  rename("a", "A"), would work, rename("A", "A"), when the file was actually
  spelled "a" would not.
- rmdir() frivolously walked up a directory before deleting, which for some
  strange reason sometimes actually worked.
- readdir() would return ENOENT when the end of the directory was reached,
  which is contrary to the way UN*X does it.
- GUSI would try to open all network services whose socket families were
  linked  in at a very early stage in the application. This would cause
  problems for SLIP/PPP (and probably also ARA) users, as for some applications
  (like MacPerl), starting up SLIP every time made little sense. Additionally,
  initializing MacTCP before the rest of the Toolbox would cause crashes with
  some SLIP implementations. The behaviour of GUSI has now changed so network
  services are only initialized when the first socket is opened or another call
  necessitates it.
- A new socket family has been added in GUSIRemoteConole.o, which is currently
  not documented, so using it is not recommended.

Version 1.3.3    24Oct93

- Added automatic centering to get directory dialog if rezzed for System 7 only.
- Added a constructor for special files and folders to class TFileSpec.
- Made rename("a", "A") possible.
- Made TFileSpec and consequently GUSI file routines more robust against
  pathological paths. Path components longer than 63 chars used to trash
  memory.

Version 1.3.2    11Sep93

- In the absence of an /etc/services file, endservent() tried to fclose
  (FILE *) -1, with disastrous consequences. Thanks to Olafur Bragason for
  reporting this bug.
- Paul C. Aitkenhead discovered that accept() for TCP sockets didn't fill
  in the name of the connecting peer.
- The tests will now initialize QuickDraw by themselves, to take into account
  the fact that when using SIOW, WaitNextEvent might get called before SIOW has
  a chance to initialize the Toolbox.
- As Brad Pickering found out, sends for UDP sockets would by mistake never
  report errors.

Version 1.3.1  09Aug93

- Reid Simmons brought to my attention that gethostname() was no longer an
  external symbol. On closer inspection, the same turned out to be true about
  truncate() and GUSIDefaultSpin(). I had made a few mistakes in my prototypes.
  The new version of the Internalize script should catch this type of error in
  the future.

Version 1.3.0    31Jul93

- Separated examples into their own folder with their own Makefile. Building
  GUSITest will therefore no longer cause GUSI.o to be rebuilt.
- The Makefile has been generally sanitized.
- All header files now reside in :includes
- Most headers have changed in rather drastical ways. The BSD headers are now
  taken from net2 and are prototyped. This is initially likely to produce a
  few errors in your code where typecasts have been missing. In particular, the
  following have changed:
   - bind, connect, accept, and getsockname take address parameters
      of type (struct sockaddr *).
    - If you had declard any variables as (dirent *), you will have to change
      that to (struct dirent *).
- The headers have also been adapted so that no symbol from the standard MPW
  headers is ever redefined in an incompatible way (hopefully).
- getserv...() has been enhanced, thanks to code contributed by Sak Wathanasin.
  The new implementation first searches for a file /etc/services in the
  preferences folder, before falling back on the old approach.
- getservent(), setervent(), endservent(), getservbyport(), truncate(),
  ftruncate(), and scandir() were added.
- stat() on a directory now returns the number of files in st_size. Needless to
  say, this is totally nonportable.
- Pathnames where an intermediate folder existed as a file didn't give the
  errors they should have given.
- Another UDP fix.

Version 1.2.0    20Jun93

- Fixed a disastrous bug with configuration resources. MPW Tools that had no
  configuration resources would "borrow" resources of other Tools previously
  loaded.
- It is now possible to make the type & creator of newly created file dependent
  on their suffixes (i.e., anything ening in .o can be mapped to 'OBJ '/'MPS ')
- If socket creation fails due to low memory conditions, errno is set correctly
- Opening of the console is now handled more subtly, allowing programmers to link
  GUSI with their custom "Dev:Console" handlers.
- The routine for checking for Command-period is now exported
- getsockname() for UDP sockets in an early stage of their existence would in
  some cases nonsense. Thanks to Paul C. Aitkenhead for discovering.
- Changed sa_constr_ppc. The old version was basically unable to provide a real
  constraint. Hopefully, though, old sa_constr_ppc records are still handled
  correctly.
- Bracketed all headers defining prototypes with #ifdef __cplusplus
  incantations. Thanks to John W. Pope for suggesting this.

Version 1.1.1    04Apr93

- A few of the declarations in sys/fcntl.h were inconsistent with Fcntl.h and
  the actual behaviour of GUSI, in particular O_CREATE. (thanks to Franklin Chen
  for reporting).
- PAP sockets would lose data when closed.

Version 1.1.0    14Mar93

- Reorganized the way to specify parts of GUSI to include. There are no
  specialized builds like GUSI_AFU.o anymore. Instead, you specify one or several
  configuration files in addition to GUSI.o in the link. If you just want to
  include everything possible, use {CLibraries}GUSI_Everything.cfg.
- Added support for the Printer Access Protocol (PAP): You can open a connection
  to the currently chosen LaserWriter with open("Dev:Printer").
- Added support for Dave Peterson's forthcoming inetd.
- Introduced fgetfileinfo().
- All header files are now protected against multiple inclusion, as suggested by
  J.T. Conklin.
- st_nlink in statbufs used to return 1 for both files and folders. While it
  might be argued that this is true, it breaks some Unix programs. Therefore,
  the current version returns for folders either the number of items the folder
  contains + 2 or the number of subdirectories the folder contains + 2 (the 2 is
  an Unixism), depending on a flag in the configuration resource (thanks to
  Charlie Reiman for reporting).
- fstat() used to claim that sockets were regular files. This bug had horrible
  consequences for some Unix software. Now, they correctly declare sockets to be
  such.
- Use FSpMakeFSSpec at some places in TFileSpec if it's available. Added a member
  function Bless() to guarantee the kosherness of a TFileSpec.
- Found a few severe bugs in GUSIBuffer. PPC sockets might work better now.
- Added several new options to the preference resource. To specify which version
  of the preference resource you want, #define GUSI_PREF_VERSION to the version
  you want. If you don't, version '0102' is assumed.
- To faciliate changing flags on the fly, programs rezzed with GUSI.r now include
  a TMPL for the version resource.

Version 1.0.2    24Jan93

- rename() used to sometimes do the wrong thing if both the name and the folder
  had to be changed. I don't think the new version is 100% correct, but it
  should be better. (thanks to Brad Pickering for reporting)
- choose() for files doesn't count the terminating NULL byte anymore. I hope
  nobody relied on the old version. (thanks again to Brad Pickering)
- getserv...() and getprotoby...() used to return NULL for the aliases field,
  which is not correct.
- TCP/IP sockets had a horrible bug with fast read/writes. That's what I get for
  not doing my code stealing properly.

Version 1.0.1    09Jan93

- If a TCP socket returned from accept() was closed, further accepts on the
  parent socket were disabled. Fixed. Thanks to Chen JiaTyan for reporting.
- GUSI configuration resources are now respected
- Programs linked with GUSI now by default automatically call the spin routine
  for every read/write (This can be turned off in the configuration resource).
- Add a chdir()-respecting fsetfileinfo()

Version 1.0        20Dec92

- Changed the way subset libraries were built.
- Arrange for the GUSI_F variant to be always built.
- Add routines to access FSSpec manipulations from plain C.
- Add correct prototypes to netdb.h.
- Rename GUSIFSp_P.h to TFileSpec.h and make it public.
- Let choose() treat flags consistently for all address families: If CHOOSE_NEW
  or CHOOSE_DIR are specified for a family that doesn't support them, EINVAL
  is returned.
- FileSocketDomain::choose() now treats CHOOSE_DEFAULT correctly
- Add getcwd()
- stat() now considers files with type 'TEXT' as executable (this is certainly
  controversial and might be made configurable in a future version).
- removed GUSIResident, the feature from hell. I forgot twice to specify
  a resident segment for it, and both times it took me almost a week to find
  the bug. The routines formerly in GUSIResident are now in Main.
- fixed a few bugs.
- Updated the documentation.

Version 1.0b4    29Oct92

Purged (hopefully) the last remaining traces of the obsolete structure name
"direct" (should have been "dirent"). Thanks to Kevin Willey for pointing out
that bug.

Version 1.0b3    19Oct92

Fixed a few bugs in the test programs

Version 1.0b2    05Oct92

The documentation is now almost complete.

Version 1.0b1    28Sep92

This release is somewhat premature. Although I believe the code is already in a
decent shape, the documentation is still in a bad shape. I wouldn't trust the PPC
Toolbox code too much yet.